Skip to content

lib.modules: refactor into composable layers with flag ordering#147

Merged
Lassulus merged 7 commits intomainfrom
refactor/modules-and-flags
Apr 7, 2026
Merged

lib.modules: refactor into composable layers with flag ordering#147
Lassulus merged 7 commits intomainfrom
refactor/modules-and-flags

Conversation

@Lassulus
Copy link
Copy Markdown
Owner

@Lassulus Lassulus commented Apr 5, 2026

Refactor lib/modules into composable layers and add priority-based flag ordering.

  • Extract command base module from wrapper.nix with shared command spec (args, env, hooks, exePath) used by both wrapper and systemd outputs
  • Extract flags module with per-flag ordering via { value, order } submodules (shorthand still works, reading returns clean values)
  • Move "$@" from wrapper template into default args in wrapPackage, and inject at order 1001 in wrapper.nix so passthrough positioning is controllable
  • Change flagSeparator default from " " to null for correct semantics
  • Add CHANGELOG documenting breaking changes

Module hierarchy:

package.nix    (pkgs, package, passthru)
flags.nix      (flags, flagSeparator, _orderedFlags -> sets config.args via mkOrder)

command.nix    (imports both, declares options.args, adds: exePath, binName, env, extraPackages, hooks)
    |
    +-- wrapper.nix    (filesToPatch, filesToExclude, patchHook -> outputs.wrapper)
    +-- systemd.nix    (systemd config -> outputs.systemd-user, outputs.systemd-system)

Flag ordering example:

flags."--config" = "/etc/foo";                            # order 1000 (default)
flags."--early"  = { value = true; order = 500; };        # before other flags
flags."--late"   = { value = true; order = 1500; };       # after "$@"
# "$@" is injected by wrapper.nix at order 1001

flagSeparator semantics:

null  -> ["--flag" "value"]  (separate argv entries, new default)
"="   -> ["--flag=value"]    (joined)
" "   -> ["--flag value"]    (joined with space, single arg)

Lassulus added 6 commits April 5, 2026 01:21
The wrapper and systemd modules share a common command specification
(package, args, env, flags, hooks). Extract these shared options into
a new command.nix base module, making wrapper one output format
alongside systemd rather than the core abstraction.

- Create lib/modules/command.nix with shared options (flags, args, env,
  exePath, binName, extraPackages, preHook, postHook)
- Slim wrapper.nix to only wrapper-specific options (filesToPatch,
  filesToExclude, patchHook) and move output to outputs.wrapper
- Add backward-compat alias for config.wrapper
Extract flags/flagSeparator into a new flags.nix module, separate from
command.nix. Flags now support per-flag ordering via { value, order }
submodules with coercion so the shorthand (flags."--foo" = "bar") still
works. Reading config.flags returns clean values (apply strips order).
An internal _orderedFlags option preserves order info, and args are
generated using mkOrder per-flag so listOf merge handles positioning.
Instead of hardcoding "$@" in the wrapper template, inject it into the
args list at order 1001 (just after the default flag order of 1000).
This makes passthrough argument positioning controllable via the
ordering system — flags with order > 1001 appear after "$@".

The wrapper module passes a custom wrapper function to wrapPackage
that omits the hardcoded "$@" since it's now part of args.

Add flags-order check verifying: --early (500) < --greeting (1000) <
"$@" (1001) < --late (1500).
The " " default was confusing: it didn't join with a space but produced
separate argv entries. Change the default to null which clearly means
"separate argv entries", while " " now actually joins with a space
(single arg). This makes the semantics consistent with "=".

null  → ["--flag" "value"]  (separate args, default)
"="   → ["--flag=value"]    (joined)
" "   → ["--flag value"]    (joined with space)
Instead of hardcoding "$@" in the wrapper template, include it in the
default args list. The template no longer appends "$@" on its own.

This means passing explicit args to wrapPackage gives full control
over whether "$@" is included. The default args (from flags) still
append "$@" for backward compatibility.

Removes the custom wrapper function override from wrapper.nix since
wrapPackage's template no longer conflicts with the module's "$@"
injection.

Add CHANGELOG documenting breaking changes.
Copy link
Copy Markdown
Collaborator

@zimward zimward left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

generally looks quite good, especially pulling the options out into their own modules

@Lassulus Lassulus force-pushed the refactor/modules-and-flags branch from 4aa05ee to 1255994 Compare April 7, 2026 20:12
@Lassulus Lassulus merged commit 9d8397d into main Apr 7, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants